home *** CD-ROM | disk | FTP | other *** search
Text File | 1996-04-05 | 11.5 KB | 440 lines | [TEXT/MWPR] |
- Sherlock Macros
-
- Overview
-
- This chapter discusses all of Sherlock's macros. Sherlock’s macros expand into actual code only
- if SHERLOCK is defined. The value assigned to the variable SHERLOCK does not matter, only
- whether it is defined or not. Define SHERLOCK before including "sl.h".
-
-
- Most Sherlock macros define tracepoints. Tracepoints are named locations within your program.
- Tracepoints are either enabled or disabled. On the Macintosh, you enabled or disable tracepoints
- either from a simulated command line or from the Sherlock menu. See the Chapter called
- “Installing Sherlock” for full details.
-
-
- Most Sherlock macros are tracing macros: these macros contain executable statements, called
- tracepoint actions, which are executed when control reaches the macro, but only if the macro's
- tracepoint has been enabled.
-
-
- Tracepoint actions will often be tracing statements that print the values of various variables. On
- the Macintosh, Sherlock creates and maintains a special window, called the log window, to which
- traces are sent using the es family of routines. However, you can also use fprintf or any other
- function to create traces.
-
-
- Besides tracing macros, Sherlock contains several special-purpose macros. These macros do
- tasks such as print or clear statistics, enable or disable watchpoints, or enable or disable
- tracepoints at run time.
-
-
- Macros such as STATB, TRACEPB and TICKB whose name ends in B denote entry macros.
- These macros mark the start of timing sections. Similarly, macros whose name ends in X denote
- exit macros that mark the end of timing sections.
-
-
- Sherlock measures the time spent in all timing sections. Timing sections may be nested; Sherlock
- maintains a timing stack describing all timing sections currently being executed. Each entry macro
- must be paired with a corresponding exit macro with the same tracepoint name. If an exit macro is
- omitted, a timing stack overflow will eventually result. If an extra exit macro is encountered, a
- timing stack underflow may follow. Sherlock prints a warning message and a stack traceback
- when either an overflow or an underflow is detected.
-
- Sherlock also counts the number of time each macro was executed. These count statistics are
- incremented even if a tracepoint is is disabled. Macros whose name ends in N do not update count
- statistics.
-
-
-
- Tracepoint Names
-
- Tracepoint names may contain lower case letters, numerals and the underscore character, but not
- blanks or special characters such as ( ) { } + etc. The following are valid tracepoint names:
-
-
- STAT("rose");
-
- STAT("rose25");
-
-
- The following are invalid tracepoint names:
-
-
- STAT("rose water"); // blank character
-
- STAT("wine&roses"); // & character
-
-
- Tracepoint names may start with a single minus sign. This minus sign indicates that the tracepoint
- name may only be enabled explicitly, not with a wildcard. For instance, the following both define
- the same tracepoint name, but tracing for the first statement must be enabled explicitly:
-
-
- STAT("abc"); // may be enabled via wildcard such as ++a*
-
- STAT("-abc"); // may only be enabled with ++abc
-
-
-
- The FTAG, FTAGV and SL_NAME macros
-
- The FTAG and FTAGV macros defines variables called ftag, ftagv, while the SL_NAME macro
- defines a variable whose name you supply:
-
-
- #define FTAG(s) char * ftag = s
-
- #define FTAGV(s) char * ftagv = s
-
- #define SL_NAME(name, s) char * name = s
-
-
-
- Use one of these macros to define a tracepoint name used by several macros. This reduces the
- number of strings used by Sherlock macros and also ensures that tracepoint names match. The
- next section shows how to use the FTAG macro.
-
-
-
- The STAT, STATB and STATX macros
-
- STAT takes one argument, a tracepoint name. For example:
-
-
- STAT("rose");
-
-
- STAT produces no output; its only function is to provide a label for a count statistic.
-
-
- The STATB is an entry macro that produces no output. Similarly, the STATX macro is an exit
- macro that produces no output. For example, the following measures the time spent in a function:
-
-
- int f()
-
- {
-
- FTAG("f");
-
- declarations;
-
- STATB(ftag);
-
- body of f;
-
- STATX(ftag);
-
- }
-
-
-
- The TICK, TICKB, TICKN and TICKX macros
-
- The TICK macro takes one argument, a tracepoint name. Examples:
-
-
- TICK(ftag);
-
- TICK("marigold");
-
-
- If enabled, TICK simply prints the name of the tracepoint followed by a colon. The output created
- from the second example above would look like:
-
-
- marigold:
-
-
- TICK updates the count statistic associated with the tracepoint name. TICKN is the same as TICK
- except that it does not update the count statistic.
-
-
- The TICKB and TICKX macros are the corresponding entry and exit macros. TICKB updates
- count statistics; TICKX does not.
-
-
-
- The TRACE, TRACEB, TRACEN and TRACEX macros
-
- TRACE takes two arguments. The first is a tracepoint name. The second is a list of tracepoint
- actions, consisting of one or more C language statements or blocks. Statements in the list of
- tracepoint actions are separated by semicolons as usual. For example:
-
-
- TRACE(ftag, es("variable v = "); eint(v); enl());
-
-
- The tracepoint actions consist of three statements:
-
-
- es("variable v = "); eint(v); enl();
-
-
- The tracepoint actions will be executed only if the string contained in the ftag variable has been
- enabled. Any number of C statements may appear in the list of tracepoint actions. For example:
-
-
- TRACE(ftag,
-
- struct s * p=f(arg);
-
- print_s(p); enl();
-
- );
-
-
- The tracepoint action consist of the following 3 statements:
-
-
- struct s * p=f(arg);
-
- print_s(p); enl();
-
-
- You can write any C statements in the list of tracepoint actions except initializers containing curly
- braces. Tracepoint actions may even contain other macros. For example:
-
-
- TRACE("abc"
-
- TRACE("xyz",
-
- es("abc and xyz both enabled\n")));
-
-
- The TRACEB, TRACEN and TRACEX macros work as you would expect: the TRACEN macro
- does not update count statistics, the TRACEB macro is an entry macro and the TRACEX macro is
- an exit macro.
-
-
-
-
- The TRACEP, TRACEPB, TRACEPN and TRACEPX macros
-
- The TRACEP macro works just like the TRACE macro except that TRACEP prints the name of
- the tracepoint, a colon and a space before executing the tracepoint actions. For example, the
- following two macros are equivalent:
-
-
- TRACE("daisy", es("daisy: n = "); eint(n); enl());
-
- TRACEP("daisy", es("n = "); eint(n); enl());
-
-
- Similarly, the TRACEPB, TRACEPN, and TRACEPX macros works like the corresponding
- TRACEB, TRACEN and TRACEX macros except that they print the name of the tracepoint before
- executing their tracepoint actions.
-
-
- There are no macros names TRACEBP, TRACEXP, etc. Think of TRACEP as a separate family
- from TRACEP; the P is not a suffix than can be applied to any macro.
-
-
-
- The SL_DUMP and SL_CLEAR macros
-
- The SL_DUMP macro prints out a report of all statistics gathered so far. It takes no arguments
- and can be called at any time. For example:
-
-
- SL_DUMP();
-
-
- The report contains several columns. The tracepoints column is an alphabetized list of tracepoint
- names, the ticks column gives count statistics for each tracepoint name, the times1 column gives
- non-cumulative timing statistics, the times2 column gives cumulative timing statistics and the
- tracing column indicates whether the tracepoint was enabled at the time SL_DUMP was called.
-
-
- The SL_CLEAR macro zeros all statistics. The SL_INIT macro also does this, so normally there
- is no need to use this macro. You might use this macro to begin gathering statistics about a
- selected portion of your code. Call SL_CLEAR at the start of the section and SL_DUMP at the
- end of the section.
-
-
-
-
- The SL_ON and SL_OFF macros
-
- These macros enable or disable the tracing for a single tracepoint, just as if the name of the
- tracepoint were appended to the end of the command line. Wildcard characters and disable counts
- are allowed.
-
-
- The name “trace” is a special case which enables or disables the tracing of all tracepoints.
- SL_OFF( "trace") is faster than disabling tracing for all tracepoints using wildcards because
- SL_OFF("trace") disables all tracing logic. Examples:
-
-
- SL_ON("abc");
-
- SL_OFF("*");
-
- SL_OFF("trace"); // enables all tracing logic
-
-
-
- The SL_INIT and SL_PARSE macros
-
- The SL_INIT macro should be executed before any other macro. It initializes the Sherlock
- system. SL_INIT should also be called before the w_mac_init routine. The SL_PARSE macro
- reads an argv vector looking for Sherlock arguments. Examples:
-
-
- SL_INIT();
-
- SL_PARSE(argc, argv, "++", "--");
-
-
- The "++" and "--" arguments are the prefix strings used to distinguish Sherlock arguments from
- other arguments. See the Chapter called “Installing Sherlock” for full details.
-
-
-
- The SL_WATCH macro
-
- The SL_WATCH macro specifies the starting address and length of a block. This block is checked
- whenever a sherlock macro is executed and a messages is issued whenever the block changes.
- This macro takes three arguments: the address of the first byte of the block, the length of the
- block, and a string to print in the warning message. For instance, the following watch macro
- checks to see if any NULL pointer has been used to store data.
-
-
- SL_WATCH((char *) 0, 4, "location zero");
-
- The SL_DISABLE and SL_ENABLE macros
-
- Use the SL_ENABLE and SL_DISABLE macros for greater control over SPP. Neither macro
- generates any code—they simply serve as markers for SPP. SL_DISABLE causes SPP not to
- generate macros for a function. For example,
-
-
- int f(void)
-
- {
-
- declarations;
-
- SL_DISABLE();
-
- // SPP will not generate Sherlock macros in this function.
-
- }
-
-
- The FTAG macro also will cause SPP not to generate macros for a function:
-
-
- int f(void)
-
- {
-
- FTAG("f");
-
- declarations;
-
- // SPP will not generate Sherlock macros in this function.
-
- }
-
-
- The SL_ENABLE macros forces SPP to insert macros into a function. Use this macro when a
- function starts with a Sherlock macro that you wrote yourself. For example:
-
-
- int g(void)
-
- {
-
- declarations;
-
- SL_ENABLE();
-
- TRACEP("dump", es("g = "); eint(g); enl());
-
- // SPP will generate Sherlock macros in this function.
-
- }
-
- Summary of Sherlock macros
-
-
- SL_INIT(); SL_PARSE(argc, argv, "++", "--");
-
-
- SL_INIT initializes the Sherlock system. SL_PARSE enables or disables tracepoints.
-
-
- FTAG(string); FTAGV(string);
-
- SL_NAME(name, string);
-
-
- FTAG and FTAGV define a variables named ftag and ftagv initialized to the given string.
-
- SL_NAME defines a variable with the given name initialized to the given string.
-
-
- STAT(tracepoint);
-
- STATB(tracepoint);
-
- STATX(tracepoint);
-
-
- The STAT macros increment their count statistic but produce no output.
-
-
- TICK(tracepoint);
-
- TICKB(tracepoint);
-
- TICKN(tracepoint);
-
- TICKX(tracepoint);
-
-
- The TICK macros print the name of the tracepoint.
-
-
- TRACE(tracepoint, statements); TRACEP(tracepoint, statements);
-
- TRACEB(tracepoint, statements); TRACEPB(tracepoint, statements);
-
- TRACEN(tracepoint, statements); TRACEPN(tracepoint, statements);
-
- TRACEX(tracepoint, statements); TRACEPX(tracepoint, statements);
-
-
-
- The TRACE macros execute their statements only if their tracepoints are enabled. The TRACEP
- macros print their tracepoint name and execute their statements only if their tracepoints are enabled.
-
-
- SL_CLEAR(); SL_DUMP();
-
-
- SL_CLEAR clears all statistics. SL_DUMP prints a report of all statistics.
-
-
- SL_ON(tracepoint); SL_OFF(tracepoint);
-
-
- SL_ON enables tracing for the tracepoint. SL_OFF disables tracing for a single tracepoint.
- SL_OFF("trace") disables all tracing.
-
-
- SL_ENABLE(); SL_DISABLE();
-
-
- SL_DISABLE prevents SPP from generating macros. SL_ENABLE forces SPP to generate
- macros.
-
-
- SL_WATCH(block, block, tag);
-
-
- SL_WATCH check the block on all Sherlock calls and reports when the block changes.
-